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(54) System and method to control and administer distributed object servers using first dass 
distributed objects 



(57) A networked computer system contains a 
number of host computers with servers that provide var- 
ious functionality to distributed clients on the network. 
Clients are able to access runtime information atx>ut 
servers on remote host computers, even where the cli- 
ents have only object references to the servers through 
the presence of an embedded first class object within 



each server process. The first class object can be used 
to determine the process identification of the server 
process, counts of active objects and Implementations 
in the server process, and to control tracing and logging 
functions provided by application programming inter- 
faces utilized by the server. 
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^5 FIELD OF IMVFMTIOM 

a distributed ot^ect prograSlJenlJon^^^^^^ admm,strat.ve operafons on object oriented applications operating in 

20 

BACKGROUND OF irjWFMTI^M 

code^r^rS^^^^^e^Sn^^^^^^^^^^^ ^" — ^ P-^dura, 

limited access to the code ZiT^T^T^ZS^ ZT^ ^7^°""^^"* ^uch programs generally have only 
data that are not in the address Jace S , he f^^^^ wr,Il ''f '° ''^'^^"'^ P^^'^^"^^^ °' ^^^^^ 

application need not be designed^ L Jo1?!S! k^,^^ ^ °* programming, however, an 

access each other s operaZi^od^ ^« ^"^P"^-* ^ t^-t can 

pie. in 6^, a class dSiS is Ta Sutes^^^^^^ programming environment. For exam- 

cannot be manipulated brothrSi^ s duSa « . ' ' T ""'^ « ^°'"P»«. 

such as Smalltalk , a clas^dLt^^^^^fs ^^^^^^^^^ r^'"^" '^"^"ages, 

cation. * "'^^^ ''^^"^^ " be manipulated during execution of the appli- 

on va'JoriSirrslaTprvr^^^^^ typically a network o, computers, where objects 

distributed object programming '""rt.onalrty to a given user. This style of application development is called 

modeTord'l^r^ro^rn::^^^^^^^^ ^ '^^'"^^^ --P"*'"9 system. One predominant 

data to client application7C cren^s a,S«^T^^^^ applications that provide operations and 

in a single corr^ut^ra it-t^^^^^^^ be d.^rtouted .n various computers on a network, or may reside 

thatinvLso7mani^late a?ob^^ 

object server, may contarmu^i^iS^ro^^^^^ ' " ^^'^^ ^ as an 

same process, a di^rXTcKeS ^St^ZT ? "^"^"^ server can reside in the 

invokes a server thrSanS;^^^^^^^^ °' " ^""^'^^ ^ <^ient 

system, that is. withoirt sp^S knShe ™ *° ^^^^^ ^^^'^^^ in the 
running. Rathe »^e S^T^Z^^l^^T^'Z °' P'^^'" '^^^'^ "^^l^^* "^'^ stored or where it s 

executSig the serv^ a Tpr^i? ar^ oasTj h T'" ^ "^'"'^ '^^"^ '^'^^'^s the computer 

server, and an^ ToJ ^TtS^ 5 arr""* ''Z''' ^° '° 

objects may be distri^ed S^aH^u^ cSrs Sn^f J^^^^^ "PP"^"""- 

p™ ^extlg n::erc: ^ r rr ^-^"^ — -st o. o, a par«cu.ar 
many objects are active wStaTe se ' r an^^^^^^ """"^ requirements or location, how 

cuting process which IT^ient Stafe infolJ I ' " ^^""^ » ^^P^-^^ on a current exe- 

includes external inforJi ^sS aJftlS^^^^^ '""^ ' ''^^"'^"'^^ °^ P^°-^^ ™^ 

ments. its configuration setup dtta anSlS^ilr^^T "T"' '! P"*^"^'"^' ^^•"'^"d argu- 
inplementations the se^S pro 'des ' """"^ ^ ^«^"P«°" °' '''^ -te^^ces and 
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Most operating systems, such as UNIX®, provide system calls useful for determining dynamic information about 
the applications that are currently executing or ready to execute, such as how much primary memory they have been 
allocated, the address offset for the address space, which applications are currently running, on which machines, and 
the like. Such system facilities are used by application developers to debug applications during development, and by 

5 system administrators to diagnose and solve problems occurring during actual use. In conventional systems where the 
processes created by an application all reside on a single computer, information about a process executing an applica- 
tion can be obtained using conventional operating system routines. 

However, in a distributed object environment, an object server does not exist as an object, but rather as a collection 
of discrete, and possibly remotely situated, objects providing related functionality to various clients. In this environment, 

10 there is typically no means for determining the state of remote server processes. T his is for two reasons. First, there is 
no first class server object per se. but only a set of distributed objects, and thus a client cannot identify a specific server 
object for obtaining process information. Second, in a distributed object environent, the only remote constructs on which 
clients can operate at run-time are first class objects: since servers are emtxxJied by processes (e.g. UNIX® proc- 
esses), which in most computing platforms are not themselves objects, clients can not easily administrate servers. 

75 Without such information, generic debugging, error tracing, and logging are not possible, thereby impeding the devel- 
opment, debugging, and administration of applications created from distributed objects. 

Accordingly, it is desirable to provide a conrputer implemented system and method for otrtaining and modifying 
administrative information and behavior of server processes on remote computers in a distributed object programming 
environment. 

20 

SUf^f^ARY OF THE INVENTION 

TTiis invention enables the inrplementation of generic administration tools for distributed object environments by 
providing an instance of a first class distributed object (hereafter refered to as the server spy) in each server on a host 
25 machine, and by making the interface and inplementation of this server spy well suited to administrate the state and 
behavior of that server by a client holding an object reference to the server spy. 

Each server spy object provides structures and methods for obtaining and modifying runtime information for proc- 
esses created to embody the activated server. The server administrator object is used by client objects to access tiie 
server spy object for this information. The server spy object is embedded in each server during application develop- 
30 ment. by including it in a' library of runtime code that is linked into server code developed by an applications developer. 
The server spy object allows clients, both within the host computer maintaining a given server, and other remotely 
situated clients, to determine and control the operation of the server associated with the particular server spy object. 
Through the server spy object, tfie client can determine the process identifier of the server, even where the server is 
executing on a renrtote computer on the network. The client can control whether the server is subject to automatic deal 
35 location of idle resource. The client may also manipulate, through the server spy, the output of ti-acing commands that 
may be included in the server by the applications developer, and where tfiis information is output as log files. 

BRIEF DESCRIPTION OF THE DRAWINGS 

40 Figure 1 is an illustration of the system of distributed computers for using server spy objects; 

Figure 2 is an illustration of the organization of a host computer supporting various servers; 

Figure 3 is a flowchart of ttie process of automatically deallocating idle objects in a server; 

Figure 4 is a flowchart of the process for manipulating log files; 

Figure 5 is a flowchart of the process for swapping a set of log files: 
45 Figure 6 is a dataflow diagram of the method of obtaining state information about a server. 

DETAILED DESCRIPTION OF THE PREFERRED EMBODIMENT 

Referring now to f=igure 1 there is shown a hardware view of a system 100 for providing runtime information for 
50 servers on remotely disti-ibuted computers in a disb-ibuted object programming environment. The system 100 includes 
a number of host corrputers 101 connected along a network 103. Each host computer 101 includes secondary storage 
1 07 for long term storage of implementation code and data for servers and clients, and the like, an input device 1 09 and 
an output device 115 for receiving and outputting commands and data into the system 100. and an addressable mem- 
ory 1 13 for storing server (not shown) and client implementation code during execution by a processor 111. During exe- 
55 cution by the processor 111. servers exist as processes in the addressable memory 1 13. Also coupled to the network 
103 are a number of clients 105. Each client 105 is an object executing as a process in a remotely situated computer 
similar in structure to a host computer 1 0 1 , or alternatively, existing as separate processes in any of tiie host computers 
101. Each client 105 requests services or data from servers in host computers 101 on the network 103. The host com- 
puters 101 may be realized by most general purposes computers, such as a SPARCstation'" computer manufactured 
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in Jnt^n plnf ? ""^"^ 5^^^^' P"^P°^« ""^"^^^ -"^y also be adapted for use wfth the 

on!^«n. f f ! 'T"*"' ^ ° ^ ^^"'^^ « Senegal purpose operating system, such as Sun Miaosystem J^fa^ir® 

.^e_s^rdis.^edo,ry:r^^^^^^^ 

ker environmerrt ,s Sun Microsystems' Project DOE (Distributed Objects Everywhere) 

»rlHrl«hT^ *° 7?,"'^ ^' '^^^ " ^ °' ^y^'^'" 100- particularly illustrating the configuration of 

addressable memory 1 13 .n any of the host conputers 101 during runtime operation di various servers ThfaS^rsf 

'"^'"^^^ ^ °' executaWe objects for ^rm'ng vSous^^^^^ 

L?e^S^Tiotc?S 'T''^ ^"^ ^"^ ^^^^ as rn^y^in- 

rSie^ar^ hoS? -management, and system accounting information, and netv^ork interfacing with 

'5 Moreparticularly. a host computer 101 includes a number of servers 201. each providing a particular tvoe of funr 
" sttrfalTv^.T'""""'''^^"^^^^"^'^^^-"*'"^ 

Bof^^j^roirto^rr:^^^^^^^^^ 

.5 v^es an interface for clients 105 to access object implementa^o^of obTSoT^Sud^^^^^^^^ 

S r H ? V- '"T"''^ °" '"'^ ^''j^ '"plementations are actual code which rSentsTobS 

^11 T ? k":*" "^"^^^ addressable memory 113 of the host computer 101, the BOA itmaintaS 
iSS hT ? ''''''' ^"^ ^"^ ^«<^'^ 201 . Which objecteSg ^e aSe o^ 

,0 ZT^l '"P'e-T^entations of object methods are also active or inactive. In this way the BOA 225 inTeiiJ, 

^ ^*^^^^^bl« "memory 1 13 on an as-needed basis, allocating mernl to a^ve sfrJ^ 
ers 201 objects 209 and .mplementations, and deallocating memory from inactive entities ^e BO^is rtceivi a 

The BOA 225 determines whether there is an active implementation of the object 209 or method and if so the BOA 225 
passes the request to the object 209. otherwise, the BOA 225 retrieves the inplementation coS for me obilS 2^9 from 
^T^'^:SVJ,hZT new process for the invoked object. exepZg the imp^mema^^n w^Tp ^^^^^^ 
till J. ? « . deactivation of objects 209 and implementations that are no longer beina used or 

Each sen/er 201 in the host computer 101 includes a number of objects 209 each of which encaosulstP.; date 
o^lhTo?! ' ^ ^ implementing Mo aToptS^.^^^^^^^ 

thr™L^ . H °"Tf ^ 209 is manipulated by clients 05 or oler' 2^9 

h ?ono "^^^ "^"'^^ attributes, and exertions that an obfeS 2^ prS 

^ZfZTf'^'T''^'^- '^"^^'^^ fr^-m -conventional objects in Sject o^SieS pSmS^uaS^ 
-n that the nterface of an object 209 is defined in an interface definition language which is thenT«3?o an S 
merna^on language, such as or C. This allows objects 209 to have muH^plefmplen^Tnte, Ln^i^^a^ol^^^^^ 
wNle still main aning a consistently defined interface. A client 105 does not have to have any infoTr^ation a£^^^^^ 
T^^ ^ •^^'"^ntat.on of the object 209. but merely has to have the interface for the obS 209 T?,e^S^209 

addrlt "1 "^l- ' ""^"^ "^^ ^" ^^^'^^ anywhere on the netvSk 103 ind.2^n t^e 

address space of a client 1 05. or any number of host conputers 1 0 1 . by using an object refe^nce for ciiS such 
^ject ref^ence might be obtained, for exanple, through the use of a nan.ng servi^2^ a^ 'h^Ja^S^^^^ 
on the host computers 101 to access the object 209 from the object reference ^ 
Coupled to the host computer 101 by the network 103 is a naming server 227 The namina server 227 maintains . 

biding IS an a^ociation between an arbitrary object name, and an object reference uniquely iderrfyinrrobie^lSg 
"1" IIT'' t° 'r''' ""^"^'"3 '^'"^ "^'^ "^f^^ including the ob/eSg The ntm^a 

reterence can be accessed from the name, and for resolving names provided by clients 105 in order to provide an ob ect 

?"v" 2?i%tlm'- ' ^ ''"^^ -^'^ ' —201 or aiy oS 209^S 

a server 201. The naming sender 227 provides clients 105 with a service that allows access to distributed servers 20? 
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before the client 105 has an object reference. Multiple naming servers 227 may be supported, with clients 105 trans- 
parently accessing various naming sen/ers 27 on the network 103. In the prefened embodiment, a naming server 227 
is included in each host computer 101 . and supports objects 209 within the host computer 101 ; multiple naming servers 
227 then work In conjunction to provides clients 105 with object references for local objects 209. 

A factory object 21 1 may be associated with each object 209, for performing a single method that is called by a cli- 
ent 105 to create a new instance of the type of object 209. The factory object 21 1 is registered in the name space direc- 
tory 229 of the naming server 227, which is accessed by clients 105 for obtaining object references. Each factory object 
21 1 includes a static create member function that creates a new object 209 of the type specific to the factory object 211, 
and returns an object reference to the new object 209. Ah initialize function is provided in created object 209 to perform 
any needed initialization on the object's state. Typically there is only one instance of a factory object 21 1 implementation 
for each object 209 in the sender 201 , The instance of each factory object 21 1 is created when the sender 201 is installed 
in the host computer 201 and registered in the naming server 227. An object 209 need not have an associated factory 
object 21 1 , for example, where the object 209 is not public and available only to the server 201 , or where the server 201 
is designed to have a single instance of a particular type of object 209. 
15 Each server 201 also includes a server spy 213 object for determining runtime information about the server 201 , 
so that remotely situated clients 105. for example during application development and debugging, can obtain current 
process and related information. The server spy 21 3 is a distributed first class object embedded in the server 201 during 
application development. The server spy 213 differs from other objects 209 in the server 201 in that the methods and 
data of the server spy 213 operate on, and reflect, the current runtime state of the server 201 . whereas the other objects 
20 maintained by the server 201 will generally provide application methods and data. Throughout the remainder of this dis- 
closure, references to "the server" and "the sen/er spy" refer to one server 201 and its embedded server spy 213, and 
it is understood that the functionality described for these respective entities applies to each respective server 201 and 
sender spy 213 in the host conputer 101. 

When a server 201 is executed by the processor 111 it is an active process in the host computer 101, and the 
25 server spy 213 is part of that server 201 process. Accordingly, the operations and attributes of each the sender spy 213 
are with regard to the current state of server 201 process in which the server spy 213 is embedded. Thus, with multiple 
server 201 processes executing on host computer 101 at one time, there is a server spy 213 in each server 201 proc- 
ess, and each such server spy 213 reports on the particular server 201 process in which it is embedded. 

The server spy 21 3 does not persistently maintain any information, again, because the server spy 213 exists to pro- 
30 vide runtime information about a server 201 , and this information is transient and limited to the process created for the 
particular execution of the server 201 by the processor 11 1. In an alternative embodiment, a server 201 may contain 
multiple server spy objects 213, providing, for example, different levels of access to the server 201 to different user 
classes, domains, or the like. 

A server spy 213 is included in each server 201 by making it a part of a runtime library which is linked with each 
35 server 201 developed and compiled in the distributed object programming environment. The sender spy 213 is included 
in the runtime library by creating an interface definition language file, commonly known as an IDL file, defining the inter- 
face of the server spy 213. This interface may be defined by either the provider of the development environment, the 
operating system provider, or the systems programmer, to best accommodate the needs of users of the system 100. 
Separate implementation definition and implementation code files are then written to implement the methods of the 
sender spy 213; threse files are compiled and then linked into the runtime library, which is used by applications develop- 
ers to create new servers 201. Thus, the server spy 213 has an implementation like any other object 209, but the appli- 
cations developer does not have to include the server spy 213 explicitly. Rather, the sender spy 213 appears 
automatically in the servers 213 during compilation and linking. This embedding process makes all servers 201 in the 
distributed object programming environment capable of responding to a known set of messages, defined in the interface 
45 of the server spy 213. without any work by the applications developers. This allows the system administrator to develop 
generic administration tools that are guaranteed to be able to communicate with any server 201 via the server spy 213. 
Once such administration tool is the server administrator 203. which is more completely described in the related appli- 
cation referenced above. 

The sender spy 213 implements an IDL interface, and thus can be called by clients 105 which exist in processes 
50 external to the server 201 process including the server spy 21 3. This distinguishes the server spy 213 from conventional 
language specific objects that are normally linked into a server 201 or application program by the development environ- 
ment compiler and linker, since these objects are only accessible to other objects that are part of the server 201 proc- 
ess. 

Because the state of server spy 21 3 reflects the state of the server 201 at any given time, the server spy 21 3 effec- 
55 tively instantiates the server 201 as a distributed object in the system 100, providing clients 105 with the same type of 
access to the internals of the server 201 that such clients 105 have to other distributed objects 209 in system 100. In 
the absence of the server spy 213, clients 105 would be unable to determine and manipulate the server 201 in the same 
manner as any other distributed object 209. since conventionally, a server 201 or application program, when executing. 
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is merely a transient process that cannot be accessed separately by clients 1 05 in the distributed environment Accord- 
ingly, server spy 213 provides for increased flexibility and efficiency In operation and development of servers 201 

The server spy 21 3 is created when a server 201 is registrated with the object request broker environment Reqis- 
ration notifies the BOA 225 of the existence of the sender 201. particularly the path name, arguments, and enviroment 
5 for the server 201 . and which Interfaces the server 201 implements. Registration also creates a factory object 21 1 for 
those obiects209forwhich a factory 211 is publicly availaWe. binding a name specified for the factory 211 object by the 
applications programmer with an object reference in the naming server 227. TTie server spy 213 is created by an invo- 
cation of a constructor function for the server spy 21 3, In the preferred embodiment, the constructor function determines 
the server administrator 203 associated with the server 201.that the server spy 213 is to be embedded In and then 
'0 assigns the server spy 213 to that server administrator 203 by providing the object reference of the server spy 213 to 
the server administrator 203. This allows the server administrator to invoke the methods of the server spy 213 as 
needed. In embodiments where there is no server administrator 203. other methods may be employed io-make the 
server spy 213 puWically avaiaWe. During registration, the server spy 213 will execute its facilities attribute (as 
descnbed betow) to determine what tracing facilities are available In the server 201, providing this Information to the 
15 sender administrator 203. The server spy 213 may also be registered with the BOA 225 so that the server administrator 
203, or remote clients 105 may access the sender spy 213 through its object reference. 

Figure 6 illustrates the call architecture for using the server spy 213 to obtain current state information about a 
server 201. In the prefen-ed embodiment, clients 105 do not have public access to the server spy 213 Rather access 
IS obtained indirectly through the server administrator 203. A client 105 invokes 601 an appropriate method on the 
20 server administrator 203 lor obtaining current state information about the server 201 associated with the invoked server 
administrator 203. (In an alternative embodiment, the server spy 213 is publicly accessible to clients 1 05 on the network 
103, and may be invoked 601 directly). The server administrator 203 in turn calls 603 the server spy 213 for the desired 
information. The server spy 213 executes a particular method, such as those described below, either invoWnq 605 fur- 
ther methods provided in the BOA 225, or the operating system 609. or other lower level object or process The server 
25 spy 2 1 3 then returns 607 the resulting information to the server administrator 203. The server administrator 203 may 
further return 61 1 this information to the client 105, if desired by the client 105. The current state information obtained 
by the server spy 213 can include both dynamic information dependent on the server 201 process such as the process 
Identification of the server 201 . non-runtime information that alters the runtime operation of the server 201 such as the 
operation of predefined API calls in the server 201. or even configuration information, such as the execution definition 
30 Of the server 201 . 

Each server spy 213 includes a number of attributes used to transiently store and manipulate information about the 
server 201 process that the server spy 2 1 3 Is part of. but the specific functionality of the server spy 2 1 3 can vary accord- 
ing to the needs of the system administrator and other users. A pseudo-interface definition file of one embodiment of 
he interface of the server spy 213 is shown in Appendix A; the interface disclosed in Appendix A is useful to define the 
functionality of the server spy 213 as described herein. It is understood that other interface definition files may also be 
suitably used to define a server spy 213 object. Similarly, various implementation f»es can be used to implement the 
interface definition of the server spy 21 3. 

Because one of the functions of the server spy 213 is to make the server 201 available to remote client 105 as an 
observaWe process in the host computer 101. the server spy 213 includes an attribute for identifying and storing the 
process identifier provided by the operating system for the server 201 process including the server spy 21 3 An example 
of the interface for this attribute is the pid attribute. This attribute allows a client 105 that is invoking the server 201 to 
access any operating system functions that examine a process, including its memory allocation, execution time and the 
like, for determining such information about the server 201 containing the server spy 213. In the absence of the server 
spy 213. a client 105 could not obtain this information about the server 201 because the client 105 does not have a 
name or object reference for the server 201. In the preferred embodiment, the pid attribute of the server spy 213 pro- 
vides an interface to a method that calls an existing operating system function that returns the process identifier of the 
server 201 . for example, using the getpidQ command in the UNIX® operating system. With the pid attribute the server 
spy 213 will return the process id of the server 201 process to the sender administrator 203 associated with' the server 
201, which would then pass the process id to client 105. 

The server spy 21 3 also includes an attribute for determining and storing a count of the active objects 209 within 
he server 201 , that is those objects 209 which are currently running and allocated resources, particularly portions of 
the addressable memory 113. An example of the interface for this attribute is the active.oljject attribute Where the 
iriiplementatlon language of the server 201 is C++, for example, the acfive_object attribute indicates the number of C++ 
obiects 209 that exist in the server 201 to service requests originating from clients 105 in the system 100 The 
active_object attribute provides a measure of how heavily loaded the server 201 is at any one time and supports 
resource management and utilization by the client 1 05 and the operating system. 

Each server 201 contains one or more implementation, and each object 209 in server 201 belongs to exactly one 
of these implementations. The server spy 213 maintains separate counts for the number of active objects created by 
each implementation when the implementation is executing. An example is the ActiveObjects struct 
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In the preferred embodiment, the count of active objects 209 is maintained as follows. When a server 201 is initial- 
ized, a linked list of all implementations is created: this is a list of the individual classes for the object 209 provided in 
the server 201 Each implementation in the list is a header to a separate linked list of active objects 209 for that imple- 
mentation; each such linked list is updated as new instances of objects 209 of the given dass are created or destroyed. 

5 The code for creating these linked lists is provided by a runtime library that is linked into the code of the server 201 when 
the server 201 is compiled by the applications developer. The server spy 213 has direct access to these linked lists. 
When a count of active objects is requested by a client 1 05, by invocation of the active_objects attribute, the server spy 
213 traverses the linked list of implementations, and for each implementation, counts the current number of object 
instances in the linked list associated with the implementation. This count is stored in the ActiveObject struct with the 

10 name of each implementation. The server spy 213 totals the count of active objects across all implementations, and 
returns this to the client 105. Alternatively, a count of object instances for each implementation may be maintained in 
the implementation linked list, with the server spy 213 traversing only this list. In the preferred embodiment, the server 
spy 213 has exclusive access to the linked list structures, thereby ensuring an accurate count of active objects. Exclu- 
sive access prevents automatic deallocation by the reaper 21 7 because the reaper 217 cannot obtain access to the list 

15 of active objects, which is necessary to perform the deallocation. 

The server spy 213 also includes a flag for indicating whether automatic deallocation is to be performed by the 
reaper 217. An example of the interface for this attribute is the boolean attribute reaping. A client 105 may wish to dis- 
able the reaper 21 7 in order to debug the server 201 . thereby preventing the server 201 from being terminated by the 
reaper 217 during the debugging process, which may make the server 201 appear inactive for long periods of time. Sim- 

20 ilarly, a system administrator may want to disable tiie reaper 21 7 to inspect the server 201 . alter its configuration infor- 
mation, and the like. 

The reaper 21 7 is a separate thread executing in each server 201 process. When the reaping flag is set. the reaper 
217 will operate normally, automatically deallocating resources from objects 209 that have been idle for a spedfied 
period of time, as preferably established by the applications developer. To determine which objects 209 are active, ttie 
25 reaper 217 obtains exclusive access to the linked lists of active objects, as described above. Figure 3 illustrates a flow- 
chart for one embodiment of the method implemented by the reaper 217. After waking 301. the reaper 217 loop 303 
over all implementations in the server 201 in which the reaper 217 is embedded. Looping 305 over the linked list of 
active objects for each implementation, for each active object 209. the reaper 21 7 determines 307 whether the object 
209 has not been invoked within the time period specified, ttiat is, if the difference between current time and a time 
30 stamp value for the last invocation of the object 209 is greater then the specified idle time. If so. the reaper 21 7 deallo- 
cates 309 resources from the idle object 209 by indirectiy calling its destructor functions in conventional manner. Oth- 
enwise. if the reaping flag is not set. the reaper 217 will itself be inactive, and active objects in the server 201 will be 
deallocated only by explicit termination of the sen/er 201 . Alternatively, instead of a single attribute functioning a flag to 
the reaper 217, the server spy 203 may indude distinct mettiods for directly starting and stopping the reaper 217; this 
35 would allow direct manipulation of the reaping function. 

The server spy 213 includes an attribute for determining and setting the cycle time of the reaper 217. that is. how 
frequently the reaper 21 7 of each server 201 is activated by the host computer 1 01 to perform deallocation. An example 
of the interface for ttiis attribute is the reaper_cyclejime attribute. 

The server spy 21 3 also has an atfribute for determining and setting an idle time specific to the server 20 1 contain- 
40 ing the server spy 213. that is, the number of seconds during which no object 209 within the server 201 is invoked. An 
example of ttie interface for this attribute is the serverjimeout attribute. Each time an object within the server 201 is 
invoked, current time is stored in ttie server 201. Referring to Figure 3. the reaper 217 compares 311 this time value 
with the current time, and if the difference exceeds ttie spedfied idle time in the server_timeout atti-ibute. ttien the reaper 
217 deactivates 313 the server 201 by calling the sen/er administrator 203 associated with the server 201. indicating 
45 server 201 is being terminated, and then invoking a shutdown method provided by the shutdown API 223. 

The disfributed object programming environment used in system 100 supports a number of application program- 
ming interfaces (APIs) for enabling each server 201 to access various operating system calls and predefined applica- 
tion routines, such as input and output functions, user interface management, and the like. In this fashion an API alters 
the operational characteristics of a server 201 by providing functionality wittiin ttie server 201 that is not directly coded 
50 by the applications developer. Rather, an API provides ttie applications developer with set of calls ttiat can be included 
in the implementation code of an object 209 or server 201 for invoking API functions during execution. There is provided 
in each server 201 a tracing API 219. a logging API 221 . a reaper API 21 7. and a shutdown API 223. 

The ti^adng API 219 provides for control of the conditional output of diagnostic information about a server process, 
useful in the determination of errors generated at runtime, or for identifying the causes of improper results from appli- 
cation execution not involving an en-or. The logging API 221 provides for directing where such diagnostic information is 
output. Separating ttiese two functions increases the flexibility of diagnostic tools, and allows for various remote clients 
105 to individually control the logging and tracing behavior of a given server 201, The reaper API 217. provides a 
method for automatic deallocation of inactive or idle objects 209 and resources. The shutdown API 223 provides a 
method for the graceful shutdown and cleanup of ttie server 201 . 
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n»n« J ^L^" applications developer Is limited to including various API calls in the server code and perma- 

.TZ^IT"^ T '° ^ "^^^ "° "^''^ ^' dynamically conf igurirwhichAPI c2 

areexecuted once theserver 201 is corripiled into an executable application. For Lrrple, to ^ 

chan«^"^T"' "^'"'^ "^''''^ '-^^ ''^'^ tracinXat^nrtf^S'^uld S be 

' SSlXS»!T' T " ^''^'"•^'^ ^P"'^^"^"' « A?l call is always^^aWe m e^^^ 

sStm.i , •'"""^ "^^ aw^lications developer may provkJe for conditional cLol of ttie t^Se 

statements, for example to output all data stor«J in a server 201 . but only when trying to diagnose a parl^cu a o^^em 
se^'^orcSr^!:? add complexity to the server 201 Addrtionally, the applications developer wS d^C he 

. a"^;;?oa;rs:c?s^^^ 

uJl^^nr^"^^-^' ^^""'"^ ^"^^ P^'^^ applications developer the distrib- 

oS^^?3e rd^rT'Tn'^ ^''"'^ logging functions. The serOir sjy 213 

object can enaWe and configure these vanous APIs within a server 201 during execution even where the^er is 
remotely srtuated from the host computer 201 maintaining the server 201 

The tracing API 217 provides for conditional tracing control through facilities. A facility is a set of tracing flaas that 
area>j,latjeasapredef^edset. 

,he li^ P.?jrT' ''^ ^"""^ *° ♦^^'^ °^ «-«^"«°" «'^«. disk reader vli 4 arS 

n n nl! 1 h / ' "'""^ ^ ^^"'^ "^^^^"^ that implements a trace functiorSu^S 
Z ?jrlJl ''^^ programming environment, or separately provided by the appliSZs dSS 

oper The applications developer specifies in the server 201 code, at various desired locations a tracemessage s^^- 

£ S1)T " ''''' ^"^ ^" ^"'P"* A funXn prXe 

K .K^T^-^'^^^.^^*'^^* char* tracejiags, char* format. ...); where DOT TRACE is an API call orovided 

by the pacing AP, 2,9; any number of output values can be specified following the format specifiJafon 

In a distributed ob,ecX programming environment, these tracing and logging functions cannot be directiv accessed 
thlJZlr? ^P^ 213 prov'L'remote clients 105 theSy o co*^ 

221 TirJZZ^V''"'' f'l °" '''''' 213. in conjunction with the trace 2^9 anX 

221 APIs enables such users to directly manipulate tracing and logging conditions for a server 201 during execute 
by provding access to API calls that control the operation of the API functions. The applications devel^^ incorSS 
vanous desired API calls in the sender 201 application. During execution of the serJS 201 a reJ^ol^s u^^^St 
1 05 can invoke the server spy 213 to configure the operation of these calls at runtime 

.hi. ^.fT'^!"^ ^^1"^- ^^'^^^ (enable/disable) a given facility and specific trace flags avail- 

able in the facility, resulting in the generation of the output value when the trace message is enSTnt^ eJduS ex^^ 
tion of the server 201. The output of trace messages for a given server 201 are sent to the^aciTAPl Tl 7 wWch 
s^rately maintains a list of log files lor storing all trace outputs from the server 201. Tbe ,0^1?!^ us^ to deLr^^^^ 
the appropriate log file or files for the server 201 . and outputs the trace message there The sLratSn o^acina cLZl 

« thef^ljwIiTgt^ffl^f '''^''"^^^^^ 

admin provides administrator control 

conf ig configuration information 

heartbeats track heartbeats sent by server 
''^ install installation details 

object object lifecycle internal details 

reaper removal of inactive objects 

/un_verbose extensive server startup and shutdown information 

data persistent data operations 

50 

other trace facilities may be defined by the applications developer as desired in an API call to the tracing API 219 

Accordingly, to access the tracing facilities included in the server 201. the server spy 213 includes the followino 
^nctional J First, the server spy 213 is able to inform a dient 105 of what facilities are a^ilable S a s^ve^S A 
facilities attribute outputs to the client 1 05 a list of fadlrties. including for each facility a fadlity narn^a desSon of me 

ZZZZT^^^l^^T'''-:'' "J ^ "^^^ andVolean^enings ol the r ags 

11 IL!^.! ^ ^ ""^^^'^ ^"^ °' '3°'*es, with the dient 1 05 invoking an enable or L 

able method of the server spy 213. spedfying a facility name, and a set of trace flags to be set. An rxam^e^f he I,tr- 
face for these methods are the trace.enaWe () and trace disableQ methods 



15 



20 



25 



30 



35 



BNSDOCID: <EP 0735469A2_L> 



EP 0 735 469 A2 



For example, a client 105 may enable a default facility called "default" with the flags "run." and "methcxj." by passing 
the following command to the server spy 213: 
trace_enable("default''.''run:method"); 

In addition, the server spy 213 allows the client 1 05 to enable all facilities in a server 201. or all trace flags in a given 
5 facility, or both; 

trace_enable(''airrf!ag_name"); 
trace_enaljle(''facility_name".*'air); 
trace_enable("air,"air); 
Similarly, the client 105 can disable all facilities previously enabled with: 
10 trace^disablefair.-ain. 

As noted above, separation of logging and tracing functionality provides for increased flexibility in th^ control of the 
server 201. Conventionally, the operating system will support a limited number of predefined log files, these log files 
will be used to record all system information, and not just information related to a specific server 201 or host computer 
101. However, a system administrator may be interested only in a specific host computer 101 or server 201 . Accord- 
15 ingly, the server spy 213 includes methods for controlling the printing for log files specific to any individual server 201 
or host computer 1 01 . for example, with the f ile_start () method starting a new log file, specified by the user, and a com- 
plementary f ile_stop 0 method for closing and saving a log file specified by the user In the preferred embodiment of the 
sen/er spy 213. a log file structure is maintained for each set of log files, storing the name of the log file, its open mode, 
the maximum file size in megabytes, and the number of swap files, if any. When the file_start 0 method is invoked, the 
20 log file structure is passed to the method, the a new log file of the specified parameters in the log file structure is cre- 
ated. When the f ile_stop () method is invoked, only the name of the log file need by passed, after which no further output 
is written to the log file. 

To create a new log file, the server spy 213 calls the log API 221 , passing a log file path name, which in turn creates 
a new log file, and places the log file on a global list stored within the server 201 so that all trace messages and error 
25 messages are output by the trace API 219 to the new log file. Ihe designation of log files is read by the trace API 201 
of the server 201 when an enabled trace facility in encountered during execution of the server 201, the trace API 219 
automatically storing output value of the trace message in the new log file. The server spy 213 supports conventional 
exception handling for file manipulation. 

In addition, because the user, such as a system administrator, may desire to log information in the standard system 
30 log files, the server spy 21 3 includes a flag, the boolean attribute use_syslog, to control this option. When the flag is set, 
the trace API 219 and log API 221 will mirror trace output value, error information log information for the server 201 to 
the operating system's log files, otherwise this information will be stored only in the specified log files for the server 201 . 

A server 201 that has been operating for significant periods of time nnay aeate very large log files, whereas a server 
201 that is infrequently used may have a very small log file. In order to accommodate this varying behavior while effi- 
35 ciently conserving secondary storage space, the server spy 21 3 provides a method, f ile_set_max_bytes Q. for changing 
the maximum size of log files for the server 201. The server spy 213 will call the log API 221 which then stores a max- 
inmjm file size for a specified log file of the server 201. This limit value is used by the ti-ace API 219 and log API 221 
when information is output to the log files, as further described with respect to Figure 4. 

Over time, most servers 201 will exceed the size of their log files. The server spy 213 provides a system adminis- 
40 trator the ability ta specify a number of log files that can be.swapped on a rotating basis. An example of the interface for 
this method is the file_set_swap_count() method. Swapping allows a given log ffle to be examined, and either deleted 
or archived as needed, while still providing an active log file for logging the server 201 . Figure 4 shows a flowchart for 
one embodiment of a method of the log API 221 . executed by the processor 1 1 1 for setting and manipulating swappable 
log files. 

<5 To print to swap files the processor 1 1 1 prints 401 the output value of ttie trace message, or other log information 
to the designated log file, previously specified in the server 201 . The processor 1 1 1 calls 403 an operating system func- 
tion to obtain the current size of the log file. This size is compared 405 to the maximum file size as specified by a client 
1 05 via the server spy 21 3. If the file size equals or exceeds the maximum, the processor 1 1 1 cheeky 407 whether the 
swap count, number of swap files specified for use in swapping, is greater than zero. If so, the processor 1 1 1 invokes 

>o 411a swap files routine to physically swap the log files. Otherwise, the processor 1 1 1 simply resets 409 an end of file 
pointer, so that the log file is written over by new log or trace information. 

Figure 5 illustrates one embodiment of swap file method for swapping log files. In this method, the oldest of a set 
of swap files is ovenwritten by successive renaming of newer swap files. Each log file is given a name in the form of 
filename.log.i. where / is an iterated value; the main, or active log file is simply filename.log. When invoked, the trace 

>5 facility or logging function will loop 501 over the set of log files specified by the user, beginning with the value 
(swap_count-2) and iterating to zero. From the iterated value of /, a new file name of the form filename.log.i is created 
503. If a file of this name already exists 505. and it will where there is more ttian one log file, then the file is renamed 
from filename.log.i to filename.log.(i+1). This will ovenwrite each of the existing log files, beginning witti the oldest one. 
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f^namtS l"^ '""^"""^ ""^""^ ^07 from filename.log to 

T ^^Tu ^ '"^"^^ ^ '"^ '"^""^"S API 223. This method allows a client 

Tnlr """T • " environment, there is considerable difficulty in ha^ rng 

uSur r »^«°Pe'-afng system, and determining the proper target for such signals. Convention^ a 
UNO^O Ml command would be used to shutdown a given server 201. However, because of the multithreaded env^/on 
ment. mere .s no way to ensure that the proper thread in the server 201 will receive ttie kill command aS thusTe 
wrong thread ^ay be terminated. The shutdown methcxl the server spy 203 bypasses this problem by di n^^^g 

Jl^^lilTnH .K H ' r""' °' ^^^^^ 201 by system administraLTuring 

debugging and other adm.nistrat«/e functions. In addition, this method allows a server 201 to hold itself down before the 
shutdown. Wrthout such a hold down operation, a client 105 cannot be sure that a call will not come betweS a liut 
downo .nvocationand a hoW.downQ invocation, since a hoW.downQ cannot be invoked first as the shutdov^Q imZ- 
tion would be rejected, as would any client call. ^ 
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APPENDIX A 

// File: ServerSpy , idl 
// 

// © 1994 Sun Microsystems, Inc. 
// 

»ifndef _SERVER_SPY_TDL 
ft define „SERVER_Spy_IDL 

^pragma ident -@ ( ft) ServerSpy . idl 1.19 95/01/16 Sun Microsystems" 

ft include odmin/Domf Server Admin, idl > 
ftinclude < admi n / Dom f Admin. idl > 

// A single ServerSpy instance is embedded in every ODF server. 

// It provides runtime information about the server as it executes 

// and supports controlling tracing/ logging configuration. 

// It is provided to the domf as the Server Administrator for graceful 

// shutdowns when the domf daemon stops. 

// 

module Datint ( 
// 

// Structure and typedef declarations 
// 

typedef unsigned long Seconds; 
typedef unsigned long ObjectCount; 

// Interface and server version structure 

struct Version { 

unsigned long majors- 
unsigned long minor; 
string date; 

); 

// TraceFlag: used to control conditional output, 
struct TraceFlag { 

string name; 

string description; 

boolean enabled; 

); 

typedef sequence<TraceFlag> TraceFlags; 

// Facility: used to group sets of flags, 
struct Facility { 

string name; 

string description; 

TraceFlags flags; 

); 

typedef sequence<Facility> Facilities; 

exception UnknownFacility {}; 
exception UnknownTraceFlag ( 

string trace_flag; // Unknown flag 

>; 

// LogFile: a single file being logged to 
struct LogFile { 
string name; 
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string open_mode; 
float max_mbytes; 
long swap__count; 

}; 

typedef sequence<LogFile> LogFiles; 

exception FileError { // unix file error 
^ string details; // Explanation of error 

exception AlreadyOpened {); // Log file has already been opened 
exception SpecialFxle (}; // Log file is not a regular uSS file 
// and max.mbytes or swap_count >0 *u«iAriie, 
exception NotOpened {); // Not currently logging to this file 



// 

// ServerSpy interface 
// 



interface ServerSpy: DOMP.Server Admin, Observer Admin ( 

20 // Shutting down 

void shut_down_hold( 

^ in BoaDbAdmin: :HoldDownDuration hold_down 

// 

25 f I Information about the running server 

// 

// Total number of active (invoked and unreaped) objects 
readonly attribute ObjectCount active_object_count ; 

30 f I Number of active objects for the implementation, 

struct ActiveObjectCount { 

string impleffientation_naine; 
ObjectCount active_object_count ; 

}; 

typedef sequence<ActiveObjectCount> Act iveObjec t Counts; 
readonly attribute Ac tiveObject Counts active_object_co!lnts; 

// List of all facilities provided by the server, 
readonly attribute Facilities facilities; 

// 

// Inspecting and changing the behavior of the reaper 

// Get/set seconds server must be idle before reaper will shut it down, 
attribute Seconds server_timeout; 

// Get/set how often the reaper wakes up and checks for inactivity, 
attribute Seconds r e ape r_cycle_ time; 

// Get/set whether to preform automatic deactivation of objects and 
// server itself, 
attribute boolean reaping; 

// 

// Tracing control 
// 
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// Enable one or more trace flags. Flags are space-delimited 
// keywords. Either facility or flag can be "all'. 
// Adds to the currently enabled set, does not 
// override any current settings, 
void trace_enable ( 

in string facility_name, 

in string flags 
) raises (UnknownFacilicy. UnknownTraceFlag) ; 

// Disable one or more flags. To turn all tracing off, use "a 
// for both facility and flags, 
void trace_disable ( 

in string facility_naine, 

in string flags 
) raises {UnknownFacility, UnknownTraceFlag) ; 

// Check whether flags for a facility are enabled, 
boolean trace_is_enabled( 

in string facility_naine, 

in string flags 
) raises (UnknownFacility, UnknownTraceFlag) ; 

// 

// Logging output control 
// 

// Flag whether to send output to syslog daemon, 
attribute boolean use„syslog; 

// Information about log files being printed to. 
readonly attribute LogFiles log_files; 

// Start printing to a new log file, 
void file_start( 

in LogFile new_file 
) raises (FileError, AlreadyOpened, SpecialFile) ; 

// Stop printing and close a log file, 
void file_stop( 

in string name 
) raises (FileError. NotOpened) ; 

// Change the maximum size in Mb of a log file. Raises 
// NotOpened if not currently logging to this file, 
vo i d f i 1 e_s e t_max_mby t es ( 

in string file_name» 

in float max_mbytes 
) raises (FileError, NotOpened, SpecialFile); 

// Change the maximum number of swapped out log files 
// (file_name.l, .2, etc.). Raises NotOpened if not 
// currently logging to this file, 
void f ile_set_swap_count ( 

in string file_name, 

in long swap_count 
) raises (FileError, NotOpened, SpecialFile); 

// This interface's version 

readonly attribute Version spy^interface_version; 
}; // ServerSpy interface 

); 



tfendif 
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Claims 

1. A computer system ,or providing a distributed object interlace to a server executing as a server process, compris- 
executiTaraTe^^'Xr"'''^^^^^^ 

2. The computer system of claim 1 , furttier comprising- 
a machine executable structure adapted to determine a process identification code for the server^^rocess. 

2tsrs':r^^^^^ 

act.eiSroHr:jK.TX"^ 

L The computer system of claim 3 further comprising: 
primary storage for storing the server process* 

wherein: 

'^^"^ ""^"^"^ P^*^"^ ^^"^'^'^ P^o^e^ identification code 

obiect i:;i:merat:^?L^^^^^ ""^"^ ^'-^^ -^er of distinct 

Objects'"' ''^"''"^ '^'^ ^''^^^^ »° de'^^'nine the number of acf ve 

^""^ '°Z1'h "'""^ °! r °' "^''"^ ' '° "^"^ ""^s* '^'^ss object further comprises- 

idleobfeTli^rsfn^;^*^""""^'^^^^ 

objects'aT'"' "'^'"^ *° ^^'^ ^ '^^'^ ^ deallocation of Kile 

flags wShVS:Tna" ^^^'''^ '° ^ ^P-*-"^ '^cilrty and set of trace 

flags wSe^Sr'''" ^'^'^ ^ 

7. The computer system of claim 6. further comprising- 
.eser^eT^SSr^aTS^^^^^ 
faci.ities'Ste'eTvr"'"'^"''''^^ 

btjrver process executing the server, comprising the steps of 

defining an object interface definition language file for a first class object, the file specifying: 
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an interface to a first attribute or operation for obtaining a process identification number for a server process: 
an interface to a second attribute or operation for obtaining a host name for a computer executing the server 
process: 

defining an implementation file specifying source code of the first class object for implementing the first and 
5 second attributes or operations, respectively: 

compiling at least one object for performing a function of the server, the object incorporated into the server, 
to produce a server file; 

compiling the interface definition language file of the first class object to produce a set of source code files 
for interfecrng the interface definition language file of the first class object to the implementation file of the first class 
10 object: 

compiling the source code files and implementation file of the first class object to produce a first class object 

file: 

linking the first class object file to the compiled server file to produce an executable server file: and 
executing the server file to create a server process containing an instance of a first class object. 

15 

9. A computer implemented method for determining current state information about a server in a distributed object 
environment, comprising the steps of: 

receiving in a first object external to the server a request from a client object to determine current state infor- 
mation for a server: 

2^ invoking from the first object an operation on a second object known to be embedded in the server, the oper- 

ation determining the current state information of the server: 

executing the operation of the second object to determine the current state information; and 
providing the cun^ent state information to the first object. 

25 1 0. The method of claim 9, wherein the second object is a server spy object, 

11. The method of claim 9 or 10, further comprising, before the step of receiving, the step of: 

embedding in the server at least one second object, each second object having at least one operation for 
determining current state information about the server. 

30 

12. The method of one of claims 9 to 11, wherein the operation of the second object provides a process identifier for 
the server 

1 3. The method of one of claims 9 to 1 2, wherein the operation of the second object provides a count of active objects 
35 within the server. 

14. The method of one of clain^ 9 to 13. wherein the operation of the second object provides a count of object imple- 
mentations within the server. 

40 1 5, The method of one of claims 9 to 1 4. wherein the operation of the second object provides a list of tracing facilities 
within the server 

1 6. The method of claim 1 5. wherein a second operation of the second object enables at least one tracing facility within 
the server 

45 

17. The method of claim 15. wherein the second operation of the second object selectively enables at least one trace 
flag in a tracing facility 

18. The method of one of claims 9 to 1 7. wherein the operation of the second object designates a log file for outputting 
50 trace and log information for conditions resulting from execution of the server. 

19. The method of claim 18, wherein a second operation of the second object establishes a number of log files to be 
used on a rotating basis. 

55 20. The method of one of claims 9 to 1 9. wherein the operation of the second object establishes a maximum time inter- 
val for which the server can be idle, further conprising the step of: 

shutting down the server after a time interval equal to or exceeding the maximum time interval. 
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(54) System and method to control and administer distributed object servers using first class 
distritnited objects 



(57) A networked computer system contains a 
number of host computers with servers that provide var- 
ious functionality to distributed clients on the network. 
Clients are able to access runtime information about 
servers on remote host computers, even where the cli- 
ents have only object references to the servers through 
the presence of an embedded first class object within 
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each server process. The first class object can be used 
to determine the process identification of the server 
process, counts of active objects and implementations 
in the server process, and to control tracing and logging 
functions provided by application programming inter- 
faces utilized by the server. 
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